CMemStream Class

Creates a memory stream, allowing read, write and seek operations. The stream is thread-safe as of Windows 8. On earlier systems, the stream is not thread-safe. Cloning is supported as of Windows 8.

Include file: AfxNova/CStream.inc

Constructor

CONSTRUCTOR CMemStream (BYVAL pInit AS CONST BYTE PTR, BYVAL cbInit AS UINT)
Parameter Description
pInit A pointer to a buffer of size cbInit. The contents of this buffer are used to set the initial contents of the memory stream. If this parameter is NULL, the returned memory stream does not have any initial content.
cbInit The number of bytes in the buffer pointed to by pInit. If pInit is set to NULL, cbInit must be zero.

Operator CAST

Returns a pointer to the underlying IStream interface of the stream object.

OPERATOR CAST () AS IStream PTR

Methods

Name Description
Read Reads a specified number of characters from the stream into memory, starting at the current seek pointer.
Write Writes a specified number of bytes into the stream starting at the current seek pointer.
Seek Changes the seek pointer to a new location. The new location is relative to either the beginning of the stream, the end of the stream, or the current seek pointer.
GetSeekPosition Returns the seek position.
ResetSeekPosition Sets the seek position at the beginning of the stream.
SeekAtEndOfStream Sets the seek position at the end of the stream.
CopyTo Copies a specified number of bytes from the current seek pointer in the stream to the current seek pointer in another stream.
GetSize Returns the size of the stream.
SetSize Changes the size of the stream.
Clone Creates a new stream with its own seek pointer that references the same bytes as the original stream.
StreamPtr Returns a pointer to the underlying IStream interface.
GetLastResult Returns the last result code.
GetErrorInfo Returns a description of the last result code.

CMemTextStream Class

Creates a memory text stream, allowing read, write and seek operations. The stream is thread-safe as of Windows 8. On earlier systems, the stream is not thread-safe. Cloning is supported as of Windows 8.

Include file: AfxNova/CStream.inc

Constructor (CMemTextStream)

CONSTRUCTOR CMemTextStream
CONSTRUCTOR CMemTextStream (BYVAL pwszText AS CONST WSTRING PTR)
Parameter Description
pwszText Creates a memory text stream and initializes it with the content of a string. If this parameter is NULL, the returned memory stream does not have any initial content.

Operator CAST

Returns a pointer to the underlying IStream interface of the stream object.

OPERATOR CAST () AS IStream PTR

Methods

Name Description
Read Reads a specified number of characters from the stream into memory, starting at the current seek pointer.
Write Writes a specified number of bytes into the stream starting at the current seek pointer.
Append Appends a string at the end of the stream.
Seek Changes the seek pointer to a new location. The new location is relative to either the beginning of the stream, the end of the stream, or the current seek pointer.
GetSeekPosition Returns the seek position.
ResetSeekPosition Sets the seek position at the beginning of the stream.
SeekAtEndOfFile Sets the seek position at the end of the stream.
SeekAtEndOfStream Sets the seek position at the end of the stream.
CopyTo Copies a specified number of characters from the current seek pointer in the stream to the current seek pointer in another stream.
GetSize Returns the size of the stream.
SetSize Changes the size of the stream.
Clone Creates a new stream with its own seek pointer that references the same bytes as the original stream.
StreamPtr Returns a pointer to the underlying IStream interface.
GetLastResult Returns the last result code.
GetErrorInfo Returns a description of the last result code.

StreamPtr

Returns a pointer to the underlying IStream interface.

FUNCTION StreamPtr () AS IStreamPtr

Remarks

To save a memory stream to a file you can:

  1. Create an instance of the CFileStream class
  2. Get a pointer to its underlying IStream interface with CFileStream.StreamPtr
  3. Copy the contents of the memory stream to the file stream with CMemStream.CopyTo
  4. Close the file with CFileStream.Close

Read (CMemStream)

Reads a specified number of bytes from the stream into memory, starting at the current seek pointer.

FUNCTION Read (BYVAL pv AS ANY PTR, BYVAL cb AS ULONG, BYVAL pcbRead AS ULONG PTR) AS HRESULT
Parameter Description
pv A pointer to the buffer which the stream data is read into.
cb The number of bytes of data to read from the stream.
pcbRead A pointer to a ULONG variable that receives the actual number of bytes read from the stream. The number of bytes read may be zero.

Return value

S_OK (0) or an HRESULT code.

FUNCTION Read (BYVAL pv AS ANY PTR, BYVAL cb AS ULONG) AS ULONG
Parameter Description
pv A pointer to the buffer which the stream data is read into.
cb The number of bytes of data to read from the stream.

ULONG. The number characters read.

Write (CMemStream)

Writes a specified number of bytes into the stream starting at the current seek pointer.

FUNCTION Write (BYVAL pv AS ANY PTR, BYVAL cb AS ULONG, BYVAL pcbWritten AS ULONG PTR) AS HRESULT
Parameter Description
pv A pointer to the buffer that contains the data that is to be written to the stream. A valid pointer must be provided for this parameter even when cb is zero.
cb The number of bytes of data to attempt to write into the stream. This value can be zero.
pcbWritten A pointer to a ULONG variable where this method writes the actual number of bytes written to the stream. The caller can set this pointer to NULL, in which case this method does not provide the actual number of bytes written.

Return value

S_OK (0) or an HRESULT code.

FUNCTION Write (BYVAL pv AS ANY PTR, BYVAL cb AS ULONG) AS ULONG
Parameter Description
pv A pointer to the buffer that contains the data that is to be written to the stream. A valid pointer must be provided for this parameter even when cb is zero.
cb The number of bytes of data to attempt to write into the stream. This value can be zero.

Return value

The number of characters actually written.

Seek (CMemStream)

Changes the seek pointer to a new location. The new location is relative to either the beginning of the stream, the end of the stream, or the current seek pointer.

FUNCTION Seek (BYVAL dlibMove AS ULONGINT, BYVAL dwOrigin AS DWORD, _
   BYVAL plibNewPosition AS ULONGINT PTR = NULL) AS HRESULT
Parameter Description
dlibMove The displacement to be added to the location indicated by the dwOrigin parameter. If dwOrigin is STREAM_SEEK_SET, this is interpreted as an unsigned value rather than a signed value.
dwOrigin The origin for the displacement specified in dlibMove. The origin can be the beginning of the file (STREAM_SEEK_SET), the current seek pointer (STREAM_SEEK_CUR), or the end of the file (STREAM_SEEK_END). For more information about values, see the STREAM_SEEK enumeration.

Return value

HRESULT. S_OK (0) on success, or an error code on failure.

GetSeekPosition (CMemStream)

Returns the current seek position.

FUNCTION GetSeekPosition () AS ULONGINT

Return value

ULONGINT. The current seek position.

ResetSeekPosition (CMemStream)

Sets the seek position at the beginning of the stream.

FUNCTION ResetSeekPosition () AS ULONGINT

Return value

ULONGINT. The new seek position.

SeekAtEndOfStream (CMemStream)

Sets the seek position at the end of the stream.

FUNCTION SeekAtEndOfStream () AS ULONGINT

Return value

ULONGINT. The new seek position.

GetSize (CMemStream)

Returns the size of the stream in bytes.

FUNCTION GetSize () AS ULONGINT

Return value

ULONGINT. The size of the stream in bytes.

SetSize (CMemStream)

Changes the size of the stream object.

FUNCTION SetSize (BYVAL libNewSize AS ULONGINT) AS HRESULT
Parameter Description
libNewSize ULONGINT. Specifies the new size, in bytes, of the stream.

Return value

HRESULT. S_OK (0) on success, or an error code on failure.

CopyTo (CMemStream)

Copies a specified number of bytes from the current seek pointer in the stream to the current seek pointer in another stream.

FUNCTION CopyTo (BYVAL pstm AS IStream PTR, _
   BYVAL cb AS ULONGINT, _
   BYVAL pcbRead AS ULONGINT PTR = NULL, _
   BYVAL pcbWritten AS ULONGINT PTR = NULL) AS HRESULT
Parameter Description
pstm A pointer to the destination stream. The stream pointed to by pstm can be a new stream or a clone of the source stream.
cb The number of bytes of data to attempt to copy into the stream.
pcbRead A pointer to the location where this method writes the actual number of bytes read from the source. You can set this pointer to NULL. In this case, this method does not provide the actual number of bytes read.
pcbWritten A pointer to the location where this method writes the actual number of bytes written to the destination. You can set this pointer to NULL. In this case, this method does not provide the actual number of bytes written.

Return value

HRESULT. S_OK (0) on success, or an error code on failure.

Clone (CMemStream)

Creates a new stream with its own seek pointer that references the same bytes as the original stream. The Clone method creates a new stream for accessing the same bytes but using a separate seek pointer. The new stream sees the same data as the source-stream. Changes written to one stream are immediately visible in the other. Range locking is shared between the streams. The initial setting of the seek pointer in the cloned stream instance is the same as the current setting of the seek pointer in the original stream at the time of the clone operation.

FUNCTION Clone (BYVAL ppstm AS IStream PTR PTR) AS HRESULT
Parameter Description
ppstm When successful, pointer to the location of an IStream pointer to the new stream. If an error occurs, this parameter is NULL.

Return value

HRESULT. S_OK (0) on success, or an error code on failure.

GetLastResult (CMemStream)

Returns the last result code.

FUNCTION GetLastResult () AS HRESULT

Return value

HRESULT. S_OK (0) on success, or an error code on failure.

GetErrorInfo (CMemStream)

Returns a description of the last result code.

FUNCTION GetErrorInfo () AS CWSTR

Return value

A description of the last result code. If the result code is S_OK (0), it returns “Success”; otherwise, it returns the hexadecimal value of the error code and a description such “Seek error”, “Write fault”, “Read fault” or “Invalid argument”.

Read (CMemTextStream)

Reads a specified number of characters from the stream into memory, starting at the current seek pointer.

FUNCTION Read (BYVAL numChars AS LONG) AS CWSTR
Parameter Description
numChars The number of characters to read from the stream. Pass -1 to read all the characters from the current seek position.

Return value

The characters read.

Write (CMemTextStream)

Writes a string at the current seek position.

FUNCTION Write (BYREF wszText AS CONST WSTRING) AS ULONG
Parameter Description
wszText The string to write.

Return value

The number of characters actually written.

Append (CMemTextStream)

Appends a string at the end of the stream.

FUNCTION Append (BYREF wszText AS CONST WSTRING) AS ULONG
Parameter Description
wszText The string to append.

Return value

The number of characters actually written.

Seek (CMemTextStream)

Sets the seek position as an absolute position from the start of the stream.

FUNCTION Seek (Seek (BYVAL nPos AS ULONGINT) AS HRESULT
Parameter Description
nPos The new seek position (from 1 to the end of the stream).

Return value

HRESULT. S_OK (0) on success, or an error code on failure.

GetSeekPosition (CMemTextStream)

Returns the current seek position.

FUNCTION GetSeekPosition () AS ULONGINT

Return value

ULONGINT. The current seek position.

ResetSeekPosition (CMemTextStream)

Sets the seek position at the beginning of the stream.

FUNCTION ResetSeekPosition () AS ULONGINT

Return value

ULONGINT. The new seek position.

SeekAtEndOfStream (CMemTextStream)

Sets the seek position at the end of the stream.

FUNCTION SeekAtEndOfStream () AS ULONGINT

Return value

ULONGINT. The new seek position.

GetSize (CMemTextStream)

Returns the size of the stream in characters.

FUNCTION GetSize () AS ULONGINT

Return value

ULONGINT. The size of the stream in bytes.

SetSize (CMemTextStream)

Changes the size of the stream object.

FUNCTION SetSize (BYVAL libNewSize AS ULONGINT) AS HRESULT
Parameter Description
libNewSize ULONGINT. Specifies the new size, in characters, of the stream.

Return value

HRESULT. S_OK (0) on success, or an error code on failure.

CopyTo (CMemTextStream)

Copies a specified number of characters from the current seek pointer in the stream to the current seek pointer in another stream.

FUNCTION CopyTo (BYVAL pstm AS IStream PTR, _
   BYVAL cb AS ULONGINT, _
   BYVAL pcbRead AS ULONGINT PTR = NULL, _
   BYVAL pcbWritten AS ULONGINT PTR = NULL) AS HRESULT
Parameter Description
pstm A pointer to the destination stream. The stream pointed to by pstm can be a new stream or a clone of the source stream.
cb The number of characters of data to attempt to copy into the stream.
pcbRead A pointer to the location where this method writes the actual number of bytes read from the source. You can set this pointer to NULL. In this case, this method does not provide the actual number of bytes read.
pcbWritten A pointer to the location where this method writes the actual number of bytes written to the destination. You can set this pointer to NULL. In this case, this method does not provide the actual number of bytes written.

Return value

HRESULT. S_OK (0) on success, or an error code on failure.

Clone (CMemTextStream)

Creates a new stream with its own seek pointer that references the same bytes as the original stream. The Clone method creates a new stream for accessing the same bytes but using a separate seek pointer. The new stream sees the same data as the source-stream. Changes written to one stream are immediately visible in the other. Range locking is shared between the streams. The initial setting of the seek pointer in the cloned stream instance is the same as the current setting of the seek pointer in the original stream at the time of the clone operation.

FUNCTION Clone (BYVAL ppstm AS IStream PTR PTR) AS HRESULT
Parameter Description
ppstm When successful, pointer to the location of an IStream pointer to the new stream. If an error occurs, this parameter is NULL.

Return value

HRESULT. S_OK (0) on success, or an error code on failure.

GetLastResult (CMemTextStream)

Returns the last result code.

FUNCTION GetLastResult () AS HRESULT

Return value

HRESULT. S_OK (0) on success, or an error code on failure.

GetErrorInfo (CMemTextStream)

Returns a description of the last result code.

FUNCTION GetErrorInfo () AS CWSTR

Return value

A description of the last result code. If the result code is S_OK (0), it returns “Success”; otherwise, it returns the hexadecimal value of the error code and a description such “Seek error”, “Write fault”, “Read fault” or “Invalid argument”.